home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / Fork.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  8.9 KB  |  326 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/Fork.man,v 1.4 92/03/28 14:21:10 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_Fork tcl
  189. .BS
  190. .VS
  191. .SH NAME
  192. Tcl_Fork, Tcl_WaitPids, Tcl_DetachPids \- manage child processes
  193. .SH SYNOPSIS
  194. .nf
  195. \fB#include <tcl.h>\fR
  196. .sp
  197. int
  198. \fBTcl_Fork\fR( )
  199. .sp
  200. int
  201. \fBTcl_WaitPids\fR(\fInumPids, pidPtr, statusPtr\fR)
  202. .sp
  203. int
  204. \fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
  205. .SH ARGUMENTS
  206. .AS int *statusPtr
  207. .AP int numPids in
  208. Number of process ids contained in the array pointed to by \fIpidPtr\fR.
  209. .AP int *pidPtr in
  210. Address of array containing \fInumPids\fR process ids.
  211. .AP int *statusPtr out
  212. Address of place to store status returned by exited/suspended process.
  213. .BE
  214.  
  215. .SH DESCRIPTION
  216. .PP
  217. These procedures keep track of child processes in order to make it
  218. easier for one application to manage several children.
  219. If an application uses
  220. the UNIX \fIfork\fR and \fIwait\fR kernel calls directly,
  221. problems occur in situations like the following:
  222. .IP [1]
  223. One part of an application creates child C1.  It plans to
  224. let the child run in background, then later wait for it to
  225. complete.
  226. .IP [2]
  227. Some other part of the application creates another child C2,
  228. not knowing anything about C1.
  229. .IP [3]
  230. The second part of the application uses \fIwait\fR to wait for C2
  231. to complete.
  232. .IP [4]
  233. C1 completes before C2, so C1 is returned by the
  234. \fIwait\fR kernel call.
  235. .IP [5]
  236. The second part of the application doesn't recognize C1, so it
  237. ignores it and calls \fIwait\fR again.  This time C2
  238. completes.
  239. .IP [6]
  240. The first part of the application eventually decides to wait
  241. for its child to complete.  When it calls \fIwait\fR there are
  242. no children left, so \fIwait\fR returns an error and the
  243. application never gets to examine the exit status for C1.
  244. .PP
  245. The procedures \fBTcl_Fork\fR, \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR
  246. get around this problem by keeping a table of child processes and
  247. their exit statuses.
  248. They also provide a more flexible waiting
  249. mechanism than the \fIwait\fR kernel call.
  250. Tcl-based applications should never call \fIfork\fR and
  251. \fIwait\fR directly;  they should use \fBTcl_Fork\fR,
  252. \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR.
  253. .PP
  254. \fBTcl_Fork\fR calls \fIfork\fR and returns the result of
  255. the \fIfork\fR kernel call.
  256. If the \fIfork\fR call was successful then \fBTcl_Fork\fR also
  257. enters the new process into its internal table of child
  258. proceses.
  259. If \fIfork\fR returns an error then \fBTcl_Fork\fR returns that
  260. same error.
  261. .PP
  262. \fBTcl_WaitPids\fR calls \fIwait\fR repeatedly until one of the processes
  263. in the \fIpidPtr\fR array has exited or been killed or suspended by a
  264. signal.
  265. When this occurs, \fBTcl_WaitPids\fR returns the process
  266. identifier for the process and stores its wait status at
  267. \fI*statusPtr\fR.
  268. If the process no longer exists (it exited or was killed by a signal),
  269. then \fBTcl_WaitPids\fR removes its entry from the internal
  270. process table.
  271. If \fIwait\fR returns a process that isn't
  272. in the \fIpidPtr\fR array, \fBTcl_WaitPids\fR saves its wait
  273. status in the internal process table and calls \fIwait\fR again.
  274. If one of the processes in the \fIpidPtr\fR array has already
  275. exited (or suspended or been killed) when \fBTcl_WaitPids\fR
  276. is called, that process and its wait status are returned
  277. immediately without calling \fIwait\fR.
  278. .PP
  279. \fBTcl_WaitPids\fR provides two advantages.  First, it allows
  280. processes to exit in any order, and saves their wait statuses.
  281. Second, it allows waiting on a number of processes simultaneously,
  282. returning when any of the processes is returned by \fIwait\fR.
  283. .PP
  284. \fBTcl_DetachPids\fR is used to indicate that the application
  285. no longer cares about the processes given by the \fIpidPtr\fR
  286. array and will never use \fBTcl_WaitPids\fR to wait for them.
  287. This occurs, for example, if one or more children are to be
  288. executed in background and the parent doesn't care whether
  289. they complete successfully.
  290. When \fBTcl_DetachPids\fR is called, the internal process
  291. table entries for the processes are marked so that the
  292. entries will be removed as soon as the processes exit or
  293. are killed.
  294. .PP
  295. If none of the pids passed to \fBTcl_WaitPids\fR exists in
  296. the internal process table, then -1 is returned and \fIerrno\fR
  297. is set to ECHILD.
  298. If a \fIwait\fR kernel call returns an error,
  299. then \fBTcl_WaitPids\fR returns that same error.
  300. If a \fIwait\fR kernel call returns a process that isn't in
  301. the internal process table,  \fBTcl_WaitPids\fR panics and
  302. aborts the application.
  303. If this situation occurs, it means that a process has been
  304. created without calling \fBTcl_Fork\fR and that its exit
  305. status is about to be lost.
  306. .PP
  307. \fBTcl_WaitPids\fR defines wait statuses to have type \fIint\fR,
  308. which is correct for POSIX and many variants of UNIX. 
  309. Some BSD-based UNIX systems still use type \fIunion wait\fR for
  310. wait statuses;  it should be safe to cast a pointer to a
  311. \fIunion wait\fR structure to \fI(int *)\fR before passing
  312. it to \fBTcl_WaitPids\fR as in the following code:
  313. .nf
  314. .RS
  315.  
  316. \fBunion wait status;
  317. int pid1, pid2;
  318. \&...
  319. pid2 = Tcl_WaitPids(1, &pid1, (int *) &status);\fR
  320. .RE
  321. .fi
  322.  
  323. .SH KEYWORDS
  324. background, child, detach, fork, process, status, wait
  325. .VE
  326.